## 19.2. mSQL C API

The mSQL C API has remained relatively stable between mSQL Versions 1 and 2. However, several new functions have been added, and there have been a few changes in the existing function. Wherever a function or feature can only be used with mSQL 2, it is noted.

### 19.2.1. Datatypes

The mSQL C API uses a few defined datatypes beyond the standard C types. These types are defined in the `msql.h' header file that must be included when compiling any program that uses the MySQL library.

`m_result`

  A structure containing the results of a `SELECT` (or `SHOW`) statement. The actual output of the query must be accessed through `m_row` elements of this structure.

`m_row`

  A single row of data returned from a `SELECT` query. Output of all mSQL datatypes are stored in this type (as an array of character strings).

`m_field`

  A structure containing all of the information concerning a specific field in the table. The elements of the `m_field` structure can be directly examined and are as follows:

  char *name

    The name of the field.

  char *table

    The name of the table containing the field. This is a null value if the result set does not correspond to a real table.

  int type

    The type of the field. This is an integer corresponding to the mSQL SQL datatypes defined in the `msql.h` header file.

  int length

    The byte length of the field.

  int flags

    Zero or more option flags. The flags are accessed through the following macros:

    IS_PRI_KEY(flags)

      Returns true if the field is a primary key.

    IS_NOT_NULL(flags)

      Returns true if the field is defined as `NOT NULL`.

msqlConnect |

    int msqlConnect ( char *host )

Creates a connection to the mSQL server whose hostname or IP address is given. If a null value is passed as the argument, the connection is made to the mSQL server on the local host using Unix sockets. The return value is a database handle used to communicate with the database server. In the case of an error, -1 is returned.

#### Example

>     /* Create a connection to the database server on the local host */
>     dbh = msqlConnect( (char *)NULL );
>     if (dbh == -1) {
>        print "Error connecting!\n";
>        exit(1);
>     }

msqlSelectDB |

    int msqlSelectDB ( int sock , char *dbName )

Chooses a database for the specified connection. A database must be chosen before any queries are sent to the database server. In the case of an error, -1 is returned.

#### Example

>     /* Select the "mydatabase" database */
>     result = msqlSelectDB( dbh, "mydatabase" );
>     if (result == -1) {
>        print "Error selecting database!\n";
>        exit(1);
>     }

msqlQuery |

    int msqlQuery( int sock , char *query )

Executes the given SQL query. In mSQL 2, the return value is the number of rows affected by the query (or selected by a `SELECT` query). In mSQL 1, zero is returned upon success. In both versions, in the case of an error, -1 is returned.

#### Example

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );

msqlStoreResult |

    m_result *msqlStoreResult()

Stores the result of a `SELECT` query. This function is called immediately after calling `msqlQuery` with an SQL `SELECT` query. The results of the query are then stored in the `m_result` structure. Only after this function has been called, can other queries be sent to the database server. Every `m_result` structure must be freed using `msqlFreeResult` when you are finished with it.

#### Example

>     m_result *results;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     /* Other queries may now be submitted and the data from this query can be
>        accessed through 'results' */

msqlFreeResult |

    void msqlFreeResult ( m_result *result )

Frees the memory associated with an `m_result` structure.

#### Example

>     m_result *results;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();

>     /* Do work */

>     msqlFreeResult(results);

msqlFetchRow |

    m_row msqlFetchRow ( m_result *result )

Retrieves a single row of data from a result set. This data is placed in an `m_row` structure, which is an array of character strings. With each successive call to `msqlFetchRow`, another row is returned until there are no more rows left, then a null value is returned.

#### Example

>     m_result *results;
>     m_row *row;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     row = msqlFetchRow(results);
>     printf("The third field of the first row of the table is: %s\n", row[2]);

msqlDataSeek |

    void msqlDataSeek ( m_result *result, int pos )

Sets the cursor that tells `msqlFetchRow` which row to fetch next. Setting a position of will move the cursor to the beginning of the data. Setting the cursor to a position past the last row of data will place the cursor at the end of the data.

#### Example

>     m_result *results;
>     m_row *row;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     row = msqlFetchRow(results);
>     /* Now go back to the beginning */
>     msqlDataSeek(results, 0);

msqlNumRows |

    int msqlNumRows ( m_result *result )

Returns the number of rows in the result set.

#### Example

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     rows = msqlNumRows(results);

msqlFetchField |

    m_field *msqlFetchField ( m_result *result )

Returns the information about the fields in the result set. Each successive call to `msqlFetchField` will return a `m_field` structure for the next field until there are no more fields left, then a null value will be returned.

#### Example

>     m_field *field;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     field = msqlFetchField(results);
>     /* 'field' now contains information about the first field in the result set */
>     field = msqlFetchField(results);
>     /* 'field' now contains information about the second field in the result set */

msqlFieldSeek |

    void msqlFieldSeek ( m_result *result , int pos )

Sets the cursor that tells `msqlFetchField` which field to fetch next. Setting a position of will move the cursor to the beginning of the fields. Setting the cursor to a position past the last field places the cursor just past the last field.

#### Example

>     m_result *results;
>     m_field *field;

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     field = msqlFetchField(results);
>     /* Now go back to the beginning */
>     msqlFieldSeek(results, 0);

msqlNumFields |

    int msqlNumFields ( m_result *result )

Returns the number of fields in the result set.

#### Example

>     rows_returned = msqlQuery( dbh, "SELECT * FROM people" );
>     results = msqlStoreResult();
>     fields = msqlNumFields(results);

msqlClose |

    int msqlClose ( int sock )

Closes the connection to the mSQL database server.

#### Example

>     dbh = msqlConnect( (char *)NULL );
>     /* Do work */
>     msqlClose(dbh);

msqlListDBs |

    m_result *msqlListDBs ( int sock )

Returns an `m_result` structure containing the names of all of the databases available in the database server. Like all `m_result` structures, the return value of this function must be freed with `msqlFreeResult` when you are done with it.

#### Example

>     databases = msqlListDBs(dbh);
>     /* 'databases' now contains the names of all of the databases on the server */

msqlListTables |

    m_result *msqlListTables ( int sock )

Returns an `m_result` structure containing the names of all of the tables in the current database. Like all `m_result` structures, the return value of this function must be freed with `msqlFreeResult` when you are done with it.

#### Example

>     tables = msqlListTables(dbh);
>     /* 'tables' now contains the names of all of the tables in the
>         current database */

msqlListFields |

    m_result *msqlListFields ( int sock , char *tableName )

Returns an `m_result` structure containing the names of all of the fields in the given table. Like all `m_result` structures, the return value of this function must be freed with `msqlFreeResult` when you are done with it.

#### Example

>     fields = msqlListFields(dbh, "people");
>     /* 'fields' now contains the names of all of the fields in the
>         'people' table */

msqlListIndex |

    m_result *msqlListIndex ( int sock , char *tableName , char *index )

Returns an `m_result` structure containing information about the given index. The returned result set will contain the type of index (currently, `avl' is the only supported type), and the names of the fields contained in the index. Like all `m_result` structures, the return value of this function must be freed with `msqlFreeResult` when you are done with it.

#### Example

>     index = msqlListIndex(dbh, "people", "idx1");
>     /* 'index' now contains the information about the 'idx1' index in the 'people'
>        table */

Copyright © 2001 O'Reilly & Associates. All rights reserved.